Skip to content

feat(mcp): add opt-in permission-aware deferred tool discovery - #38

Merged
ALikesToCode merged 2 commits into
integrate/gateway-waves-1-3from
feat/deferred-tools
Oct 9, 2026
Merged

ALikesToCode merged 2 commits into
integrate/gateway-waves-1-3from
feat/deferred-tools

Conversation

@ALikesToCode

@ALikesToCode ALikesToCode commented Oct 8, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds permission-aware deferred tool discovery behind DEFERRED_TOOLS_ENABLED, which defaults to false. With the flag off, tool lists, tool calls, schemas, responses, headers and storage access are unchanged, and multillm.tools.discover returns the existing method-not-found error.

  • With the flag on, both MCP endpoints (/v1/mcp on the gateway and /mcp for Knowledge) accept multillm.tools.discover, with a query and a limit of 1–16 tools:
    • Permissions are filtered before ranking. Ranking is local word matching on names, titles and descriptions; there are no embeddings and no provider calls.
    • Every returned tool carries its complete inputSchema. A schema is never shortened: one that cannot fit returns 413 tool_schema_too_large.
    • Responses are bounded to 64 KiB.
    • Cursors are HMAC-signed and expire 120 seconds after the first page. They are bound to the principal, scopes, contract digest, grant revision, observed grant rows, query and page. A changed grant invalidates them.
  • tools/list returns only granted tools. tools/call rereads grants and validates the full argument schema before dispatch, including for tools the caller never discovered.
    • A denied call returns 403 tool_not_granted.
    • Invalid arguments return 400.
    • Missing grant storage or a missing validator returns 503.
    • Errors never echo arguments or schema contents.
  • Grants live in the new D1 table tool_grants (migration 0018):
    • The migration seeds * compatibility rows for every current tool, using the tool's existing required scope, so existing scope holders keep their access.
    • A per-principal row overrides the compatibility row, including an explicit denial.
    • Tools without a row are denied. Administrator scope does not bypass a denial.
  • The Worker validates arguments with a bounded JSON Schema validator. It covers exactly the keywords the static catalogue uses; any other keyword fails closed with 503. Flask uses the existing jsonschema library.
  • Flask reads grants through a new read-only tool_grants operation on the private model-state endpoint. The Worker reads INTELLIGENCE_DB directly.

Details are in docs/deferred-tools.md.

Known limitation

There is no admin endpoint or dashboard for editing grants yet. Operators change tool_grants rows with D1 SQL and should bump the row revision in the same statement.

Deployment

Apply migration 0018 before enabling the flag. A push to main does not apply D1 migrations:

npx wrangler d1 migrations apply multillm-intelligence --remote

Stacking

This is the first Wave 4 migration (0018). Later Wave 4 PRs that add migrations (0019–0023) stack on it, so that each PR keeps the contiguous numbering cf:migrations:check requires.

Shared registrations

  • Added tests/test_deferred_tools_worker.mjs to test:worker.
  • Added DEFERRED_TOOLS_ENABLED to the Container env keys.
  • Added tool_grants to the D1 readiness tables.
  • Added worker/knowledge/deferred-tools.mjs to the secret firewall inventory.

Tests

  • tests/test_deferred_tools.py and tests/test_deferred_tools_worker.mjs are new. They cover:
    • byte-identical behaviour with the flag off, through the real /mcp routes (allowed, scope-denied, pin-mismatch and non-object calls; discover returning -32601);
    • discovery paging, cursor expiry and revocation;
    • a denied call never reaching dispatch;
    • argument validation;
    • every catalogue schema being accepted by the Worker validator, plus a rejection for each keyword;
    • the private tool_grants read and its 503 when the table is missing.
  • After merging the updated Wave 3 base (8657ce1): full Python suite 3,583 passed, 2 skipped. ruff, mypy and bandit are clean.
  • npm run test:worker: 1,374 passed. npm run test:integration: 7 passed.
  • cf:migrations:check reports 18 contiguous, additive migrations.
  • test:deploy, free routes, client headers and the wrangler deploy --dry-run bundle all pass.
  • tests/test_frontend_build.mjs fails locally because @tailwindcss/cli is not installed. It fails the same way on main.

CI notes

  • GitHub python/node jobs: the dependency-audit steps fail on every branch, including main. fix(deps): clear the CI dependency audit advisories #42 fixes that.
  • Workers Builds: fails on this stack because the Wave 3 base adds the AdmissionCoordinator Durable Object migration, which wrangler versions upload cannot apply. This is expected until wrangler deploy runs on main.

#43 stacks on this branch.

This is part of Wave 4. It is based on integrate/gateway-waves-1-3, and the Wave 4 integration PR adds the README line.

Add multillm.tools.discover on both MCP endpoints behind DEFERRED_TOOLS_ENABLED (default off): grant-filtered local ranking with complete schemas, signed short-lived cursors, and grant and argument rechecks before every tool call. Grants live in the new tool_grants table (migration 0018) with compatibility rows for current tools.
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@coderabbitai

coderabbitai Bot commented Oct 8, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 7cf37e6d-5f2c-4726-9381-fe4b2e551b85

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Oct 8, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Updated (UTC)
❌ Deployment failed
View logs
multillm-proxy 6cabc31 Oct 09 2026, 12:31 AM

…o feat/deferred-tools

# Conflicts:
#	package.json
@ALikesToCode
ALikesToCode merged commit c7fa539 into integrate/gateway-waves-1-3 Oct 9, 2026
4 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant